home *** CD-ROM | disk | FTP | other *** search
/ MacWorld 2003 August / MW 8 2003 CD1.iso / Inside Macworld / Product News / gimp-1.2.4.sit / gimp-1.2.4 / libgimp / gimpimage_pdb.c < prev    next >
Encoding:
C/C++ Source or Header  |  2001-11-24  |  56.2 KB  |  2,169 lines
  1. /* LIBGIMP - The GIMP Library
  2.  * Copyright (C) 1995-2000 Peter Mattis and Spencer Kimball
  3.  *
  4.  * gimpimage_pdb.c
  5.  *
  6.  * This library is free software; you can redistribute it and/or
  7.  * modify it under the terms of the GNU Lesser General Public
  8.  * License as published by the Free Software Foundation; either
  9.  * version 2 of the License, or (at your option) any later version.
  10.  *
  11.  * This library is distributed in the hope that it will be useful,
  12.  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13.  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14.  * Lesser General Public License for more details.
  15.  *
  16.  * You should have received a copy of the GNU Lesser General Public
  17.  * License along with this library; if not, write to the
  18.  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  19.  * Boston, MA 02111-1307, USA.
  20.  */
  21.  
  22. /* NOTE: This file is autogenerated by pdbgen.pl */
  23.  
  24. #include <string.h>
  25.  
  26. #include "gimp.h"
  27.  
  28. /**
  29.  * gimp_image_list:
  30.  * @num_images: The number of images currently open.
  31.  *
  32.  * Returns the list of images currently open.
  33.  *
  34.  * This procedure returns the list of images currently open in the
  35.  * GIMP.
  36.  *
  37.  * Returns: The list of images currently open.
  38.  */
  39. gint *
  40. gimp_image_list (gint *num_images)
  41. {
  42.   GimpParam *return_vals;
  43.   gint nreturn_vals;
  44.   gint *image_ids = NULL;
  45.  
  46.   return_vals = gimp_run_procedure ("gimp_image_list",
  47.                     &nreturn_vals,
  48.                     GIMP_PDB_END);
  49.  
  50.   *num_images = 0;
  51.  
  52.   if (return_vals[0].data.d_status == GIMP_PDB_SUCCESS)
  53.     {
  54.       *num_images = return_vals[1].data.d_int32;
  55.       image_ids = g_new (gint32, *num_images);
  56.       memcpy (image_ids, return_vals[2].data.d_int32array,
  57.           *num_images * sizeof (gint32));
  58.     }
  59.  
  60.   gimp_destroy_params (return_vals, nreturn_vals);
  61.  
  62.   return image_ids;
  63. }
  64.  
  65. /**
  66.  * gimp_image_new:
  67.  * @width: The width of the image.
  68.  * @height: The height of the image.
  69.  * @type: The type of image.
  70.  *
  71.  * Creates a new image with the specified width, height, and type.
  72.  *
  73.  * Creates a new image, undisplayed with the specified extents and
  74.  * type. A layer should be created and added before this image is
  75.  * displayed, or subsequent calls to 'gimp_display_new' with this image
  76.  * as an argument will fail. Layers can be created using the
  77.  * 'gimp_layer_new' commands. They can be added to an image using the
  78.  * 'gimp_image_add_layer' command.
  79.  *
  80.  * Returns: The ID of the newly created image.
  81.  */
  82. gint32
  83. gimp_image_new (gint              width,
  84.         gint              height,
  85.         GimpImageBaseType type)
  86. {
  87.   GimpParam *return_vals;
  88.   gint nreturn_vals;
  89.   gint32 image_ID = -1;
  90.  
  91.   return_vals = gimp_run_procedure ("gimp_image_new",
  92.                     &nreturn_vals,
  93.                     GIMP_PDB_INT32, width,
  94.                     GIMP_PDB_INT32, height,
  95.                     GIMP_PDB_INT32, type,
  96.                     GIMP_PDB_END);
  97.  
  98.   if (return_vals[0].data.d_status == GIMP_PDB_SUCCESS)
  99.     image_ID = return_vals[1].data.d_image;
  100.  
  101.   gimp_destroy_params (return_vals, nreturn_vals);
  102.  
  103.   return image_ID;
  104. }
  105.  
  106. /**
  107.  * gimp_image_resize:
  108.  * @image_ID: The image.
  109.  * @new_width: New image width.
  110.  * @new_height: New image height.
  111.  * @offx: x offset between upper left corner of old and new images: (new - old).
  112.  * @offy: y offset between upper left corner of old and new images: (new - old).
  113.  *
  114.  * Resize the image to the specified extents.
  115.  *
  116.  * This procedure resizes the image so that it's new width and height
  117.  * are equal to the supplied parameters. Offsets are also provided
  118.  * which describe the position of the previous image's content. No
  119.  * bounds checking is currently provided, so don't supply parameters
  120.  * that are out of bounds. All channels within the image are resized
  121.  * according to the specified parameters; this includes the image
  122.  * selection mask. All layers within the image are repositioned
  123.  * according to the specified offsets.
  124.  *
  125.  * Returns: TRUE on success.
  126.  */
  127. gboolean
  128. gimp_image_resize (gint32 image_ID,
  129.            gint   new_width,
  130.            gint   new_height,
  131.            gint   offx,
  132.            gint   offy)
  133. {
  134.   GimpParam *return_vals;
  135.   gint nreturn_vals;
  136.   gboolean success = TRUE;
  137.  
  138.   return_vals = gimp_run_procedure ("gimp_image_resize",
  139.                     &nreturn_vals,
  140.                     GIMP_PDB_IMAGE, image_ID,
  141.                     GIMP_PDB_INT32, new_width,
  142.                     GIMP_PDB_INT32, new_height,
  143.                     GIMP_PDB_INT32, offx,
  144.                     GIMP_PDB_INT32, offy,
  145.                     GIMP_PDB_END);
  146.  
  147.   success = return_vals[0].data.d_status == GIMP_PDB_SUCCESS;
  148.  
  149.   gimp_destroy_params (return_vals, nreturn_vals);
  150.  
  151.   return success;
  152. }
  153.  
  154. /**
  155.  * gimp_image_scale:
  156.  * @image_ID: The image.
  157.  * @new_width: New image width.
  158.  * @new_height: New image height.
  159.  *
  160.  * Scale the image to the specified extents.
  161.  *
  162.  * This procedure scales the image so that it's new width and height
  163.  * are equal to the supplied parameters. Offsets are also provided
  164.  * which describe the position of the previous image's content. No
  165.  * bounds checking is currently provided, so don't supply parameters
  166.  * that are out of bounds. All channels within the image are scaled
  167.  * according to the specified parameters; this includes the image
  168.  * selection mask. All layers within the image are repositioned
  169.  * according to the specified offsets.
  170.  *
  171.  * Returns: TRUE on success.
  172.  */
  173. gboolean
  174. gimp_image_scale (gint32 image_ID,
  175.           gint   new_width,
  176.           gint   new_height)
  177. {
  178.   GimpParam *return_vals;
  179.   gint nreturn_vals;
  180.   gboolean success = TRUE;
  181.  
  182.   return_vals = gimp_run_procedure ("gimp_image_scale",
  183.                     &nreturn_vals,
  184.                     GIMP_PDB_IMAGE, image_ID,
  185.                     GIMP_PDB_INT32, new_width,
  186.                     GIMP_PDB_INT32, new_height,
  187.                     GIMP_PDB_END);
  188.  
  189.   success = return_vals[0].data.d_status == GIMP_PDB_SUCCESS;
  190.  
  191.   gimp_destroy_params (return_vals, nreturn_vals);
  192.  
  193.   return success;
  194. }
  195.  
  196. /**
  197.  * gimp_image_delete:
  198.  * @image_ID: The image.
  199.  *
  200.  * Delete the specified image.
  201.  *
  202.  * If there are no displays associated with this image it will be
  203.  * deleted. This means that you can not delete an image through the PDB
  204.  * that was created by the user. If the associated display was however
  205.  * created through the PDB and you know the display ID, you may delete
  206.  * the display. Removal of the last associated display will then delete
  207.  * the image.
  208.  *
  209.  * Returns: TRUE on success.
  210.  */
  211. gboolean
  212. gimp_image_delete (gint32 image_ID)
  213. {
  214.   GimpParam *return_vals;
  215.   gint nreturn_vals;
  216.   gboolean success = TRUE;
  217.  
  218.   return_vals = gimp_run_procedure ("gimp_image_delete",
  219.                     &nreturn_vals,
  220.                     GIMP_PDB_IMAGE, image_ID,
  221.                     GIMP_PDB_END);
  222.  
  223.   success = return_vals[0].data.d_status == GIMP_PDB_SUCCESS;
  224.  
  225.   gimp_destroy_params (return_vals, nreturn_vals);
  226.  
  227.   return success;
  228. }
  229.  
  230. /**
  231.  * gimp_image_free_shadow:
  232.  * @image_ID: The image.
  233.  *
  234.  * Free the specified image's shadow data (if it exists).
  235.  *
  236.  * This procedure is intended as a memory saving device. If any shadow
  237.  * memory has been allocated, it will be freed automatically on a call
  238.  * to 'gimp_image_delete'.
  239.  *
  240.  * Returns: TRUE on success.
  241.  */
  242. gboolean
  243. gimp_image_free_shadow (gint32 image_ID)
  244. {
  245.   GimpParam *return_vals;
  246.   gint nreturn_vals;
  247.   gboolean success = TRUE;
  248.  
  249.   return_vals = gimp_run_procedure ("gimp_image_free_shadow",
  250.                     &nreturn_vals,
  251.                     GIMP_PDB_IMAGE, image_ID,
  252.                     GIMP_PDB_END);
  253.  
  254.   success = return_vals[0].data.d_status == GIMP_PDB_SUCCESS;
  255.  
  256.   gimp_destroy_params (return_vals, nreturn_vals);
  257.  
  258.   return success;
  259. }
  260.  
  261. /**
  262.  * gimp_image_get_layers:
  263.  * @image_ID: The image.
  264.  * @num_layers: The number of layers contained in the image.
  265.  *
  266.  * Returns the list of layers contained in the specified image.
  267.  *
  268.  * This procedure returns the list of layers contained in the specified
  269.  * image. The order of layers is from topmost to bottommost.
  270.  *
  271.  * Returns: The list of layers contained in the image.
  272.  */
  273. gint *
  274. gimp_image_get_layers (gint32  image_ID,
  275.                gint   *num_layers)
  276. {
  277.   GimpParam *return_vals;
  278.   gint nreturn_vals;
  279.   gint *layer_ids = NULL;
  280.  
  281.   return_vals = gimp_run_procedure ("gimp_image_get_layers",
  282.                     &nreturn_vals,
  283.                     GIMP_PDB_IMAGE, image_ID,
  284.                     GIMP_PDB_END);
  285.  
  286.   *num_layers = 0;
  287.  
  288.   if (return_vals[0].data.d_status == GIMP_PDB_SUCCESS)
  289.     {
  290.       *num_layers = return_vals[1].data.d_int32;
  291.       layer_ids = g_new (gint32, *num_layers);
  292.       memcpy (layer_ids, return_vals[2].data.d_int32array,
  293.           *num_layers * sizeof (gint32));
  294.     }
  295.  
  296.   gimp_destroy_params (return_vals, nreturn_vals);
  297.  
  298.   return layer_ids;
  299. }
  300.  
  301. /**
  302.  * gimp_image_get_channels:
  303.  * @image_ID: The image.
  304.  * @num_channels: The number of channels contained in the image.
  305.  *
  306.  * Returns the list of channels contained in the specified image.
  307.  *
  308.  * This procedure returns the list of channels contained in the
  309.  * specified image. This does not include the selection mask, or layer
  310.  * masks. The order is from topmost to bottommost.
  311.  *
  312.  * Returns: The list of channels contained in the image.
  313.  */
  314. gint *
  315. gimp_image_get_channels (gint32  image_ID,
  316.              gint   *num_channels)
  317. {
  318.   GimpParam *return_vals;
  319.   gint nreturn_vals;
  320.   gint *channel_ids = NULL;
  321.  
  322.   return_vals = gimp_run_procedure ("gimp_image_get_channels",
  323.                     &nreturn_vals,
  324.                     GIMP_PDB_IMAGE, image_ID,
  325.                     GIMP_PDB_END);
  326.  
  327.   *num_channels = 0;
  328.  
  329.   if (return_vals[0].data.d_status == GIMP_PDB_SUCCESS)
  330.     {
  331.       *num_channels = return_vals[1].data.d_int32;
  332.       channel_ids = g_new (gint32, *num_channels);
  333.       memcpy (channel_ids, return_vals[2].data.d_int32array,
  334.           *num_channels * sizeof (gint32));
  335.     }
  336.  
  337.   gimp_destroy_params (return_vals, nreturn_vals);
  338.  
  339.   return channel_ids;
  340. }
  341.  
  342. /**
  343.  * gimp_image_unset_active_channel:
  344.  * @image_ID: The image.
  345.  *
  346.  * Unsets the active channel in the specified image.
  347.  *
  348.  * If an active channel exists, it is unset. There then exists no
  349.  * active channel, and if desired, one can be set through a call to
  350.  * 'Set Active Channel'. No error is returned in the case of no
  351.  * existing active channel.
  352.  *
  353.  * Returns: TRUE on success.
  354.  */
  355. gboolean
  356. gimp_image_unset_active_channel (gint32 image_ID)
  357. {
  358.   GimpParam *return_vals;
  359.   gint nreturn_vals;
  360.   gboolean success = TRUE;
  361.  
  362.   return_vals = gimp_run_procedure ("gimp_image_unset_active_channel",
  363.                     &nreturn_vals,
  364.                     GIMP_PDB_IMAGE, image_ID,
  365.                     GIMP_PDB_END);
  366.  
  367.   success = return_vals[0].data.d_status == GIMP_PDB_SUCCESS;
  368.  
  369.   gimp_destroy_params (return_vals, nreturn_vals);
  370.  
  371.   return success;
  372. }
  373.  
  374. /**
  375.  * gimp_image_pick_correlate_layer:
  376.  * @image_ID: The image.
  377.  * @x: The x coordinate for the pick.
  378.  * @y: The y coordinate for the pick.
  379.  *
  380.  * Find the layer visible at the specified coordinates.
  381.  *
  382.  * This procedure finds the layer which is visible at the specified
  383.  * coordinates. Layers which do not qualify are those whose extents do
  384.  * not pass within the specified coordinates, or which are transparent
  385.  * at the specified coordinates. This procedure will return -1 if no
  386.  * layer is found.
  387.  *
  388.  * Returns: The layer found at the specified coordinates.
  389.  */
  390. gint32
  391. gimp_image_pick_correlate_layer (gint32 image_ID,
  392.                  gint   x,
  393.                  gint   y)
  394. {
  395.   GimpParam *return_vals;
  396.   gint nreturn_vals;
  397.   gint32 layer_ID = -1;
  398.  
  399.   return_vals = gimp_run_procedure ("gimp_image_pick_correlate_layer",
  400.                     &nreturn_vals,
  401.                     GIMP_PDB_IMAGE, image_ID,
  402.                     GIMP_PDB_INT32, x,
  403.                     GIMP_PDB_INT32, y,
  404.                     GIMP_PDB_END);
  405.  
  406.   if (return_vals[0].data.d_status == GIMP_PDB_SUCCESS)
  407.     layer_ID = return_vals[1].data.d_layer;
  408.  
  409.   gimp_destroy_params (return_vals, nreturn_vals);
  410.  
  411.   return layer_ID;
  412. }
  413.  
  414. /**
  415.  * gimp_image_raise_layer:
  416.  * @image_ID: The image.
  417.  * @layer_ID: The layer to raise.
  418.  *
  419.  * Raise the specified layer in the image's layer stack
  420.  *
  421.  * This procedure raises the specified layer one step in the existing
  422.  * layer stack. It will not move the layer if there is no layer above
  423.  * it, or the layer has no alpha channel.
  424.  *
  425.  * Returns: TRUE on success.
  426.  */
  427. gboolean
  428. gimp_image_raise_layer (gint32 image_ID,
  429.             gint32 layer_ID)
  430. {
  431.   GimpParam *return_vals;
  432.   gint nreturn_vals;
  433.   gboolean success = TRUE;
  434.  
  435.   return_vals = gimp_run_procedure ("gimp_image_raise_layer",
  436.                     &nreturn_vals,
  437.                     GIMP_PDB_IMAGE, image_ID,
  438.                     GIMP_PDB_LAYER, layer_ID,
  439.                     GIMP_PDB_END);
  440.  
  441.   success = return_vals[0].data.d_status == GIMP_PDB_SUCCESS;
  442.  
  443.   gimp_destroy_params (return_vals, nreturn_vals);
  444.  
  445.   return success;
  446. }
  447.  
  448. /**
  449.  * gimp_image_lower_layer:
  450.  * @image_ID: The image.
  451.  * @layer_ID: The layer to lower.
  452.  *
  453.  * Lower the specified layer in the image's layer stack
  454.  *
  455.  * This procedure lowers the specified layer one step in the existing
  456.  * layer stack. It will not move the layer if there is no layer below
  457.  * it, or the layer has no alpha channel.
  458.  *
  459.  * Returns: TRUE on success.
  460.  */
  461. gboolean
  462. gimp_image_lower_layer (gint32 image_ID,
  463.             gint32 layer_ID)
  464. {
  465.   GimpParam *return_vals;
  466.   gint nreturn_vals;
  467.   gboolean success = TRUE;
  468.  
  469.   return_vals = gimp_run_procedure ("gimp_image_lower_layer",
  470.                     &nreturn_vals,
  471.                     GIMP_PDB_IMAGE, image_ID,
  472.                     GIMP_PDB_LAYER, layer_ID,
  473.                     GIMP_PDB_END);
  474.  
  475.   success = return_vals[0].data.d_status == GIMP_PDB_SUCCESS;
  476.  
  477.   gimp_destroy_params (return_vals, nreturn_vals);
  478.  
  479.   return success;
  480. }
  481.  
  482. /**
  483.  * gimp_image_raise_layer_to_top:
  484.  * @image_ID: The image.
  485.  * @layer_ID: The layer to raise to top.
  486.  *
  487.  * Raise the specified layer in the image's layer stack to top of stack
  488.  *
  489.  * This procedure raises the specified layer to top of the existing
  490.  * layer stack. It will not move the layer if there is no layer above
  491.  * it, or the layer has no alpha channel.
  492.  *
  493.  * Returns: TRUE on success.
  494.  */
  495. gboolean
  496. gimp_image_raise_layer_to_top (gint32 image_ID,
  497.                    gint32 layer_ID)
  498. {
  499.   GimpParam *return_vals;
  500.   gint nreturn_vals;
  501.   gboolean success = TRUE;
  502.  
  503.   return_vals = gimp_run_procedure ("gimp_image_raise_layer_to_top",
  504.                     &nreturn_vals,
  505.                     GIMP_PDB_IMAGE, image_ID,
  506.                     GIMP_PDB_LAYER, layer_ID,
  507.                     GIMP_PDB_END);
  508.  
  509.   success = return_vals[0].data.d_status == GIMP_PDB_SUCCESS;
  510.  
  511.   gimp_destroy_params (return_vals, nreturn_vals);
  512.  
  513.   return success;
  514. }
  515.  
  516. /**
  517.  * gimp_image_lower_layer_to_bottom:
  518.  * @image_ID: The image.
  519.  * @layer_ID: The layer to lower to bottom.
  520.  *
  521.  * Lower the specified layer in the image's layer stack to bottom of
  522.  * stack
  523.  *
  524.  * This procedure lowers the specified layer to bottom of the existing
  525.  * layer stack. It will not move the layer if there is no layer below
  526.  * it, or the layer has no alpha channel.
  527.  *
  528.  * Returns: TRUE on success.
  529.  */
  530. gboolean
  531. gimp_image_lower_layer_to_bottom (gint32 image_ID,
  532.                   gint32 layer_ID)
  533. {
  534.   GimpParam *return_vals;
  535.   gint nreturn_vals;
  536.   gboolean success = TRUE;
  537.  
  538.   return_vals = gimp_run_procedure ("gimp_image_lower_layer_to_bottom",
  539.                     &nreturn_vals,
  540.                     GIMP_PDB_IMAGE, image_ID,
  541.                     GIMP_PDB_LAYER, layer_ID,
  542.                     GIMP_PDB_END);
  543.  
  544.   success = return_vals[0].data.d_status == GIMP_PDB_SUCCESS;
  545.  
  546.   gimp_destroy_params (return_vals, nreturn_vals);
  547.  
  548.   return success;
  549. }
  550.  
  551. /**
  552.  * gimp_image_merge_visible_layers:
  553.  * @image_ID: The image.
  554.  * @merge_type: The type of merge.
  555.  *
  556.  * Merge the visible image layers into one.
  557.  *
  558.  * This procedure combines the visible layers into a single layer using
  559.  * the specified merge type. A merge type of EXPAND_AS_NECESSARY
  560.  * expands the final layer to encompass the areas of the visible
  561.  * layers. A merge type of CLIP_TO_IMAGE clips the final layer to the
  562.  * extents of the image. A merge type of CLIP_TO_BOTTOM_LAYER clips the
  563.  * final layer to the size of the bottommost layer.
  564.  *
  565.  * Returns: The resulting layer.
  566.  */
  567. gint32
  568. gimp_image_merge_visible_layers (gint32        image_ID,
  569.                  GimpMergeType merge_type)
  570. {
  571.   GimpParam *return_vals;
  572.   gint nreturn_vals;
  573.   gint32 layer_ID = -1;
  574.  
  575.   return_vals = gimp_run_procedure ("gimp_image_merge_visible_layers",
  576.                     &nreturn_vals,
  577.                     GIMP_PDB_IMAGE, image_ID,
  578.                     GIMP_PDB_INT32, merge_type,
  579.                     GIMP_PDB_END);
  580.  
  581.   if (return_vals[0].data.d_status == GIMP_PDB_SUCCESS)
  582.     layer_ID = return_vals[1].data.d_layer;
  583.  
  584.   gimp_destroy_params (return_vals, nreturn_vals);
  585.  
  586.   return layer_ID;
  587. }
  588.  
  589. /**
  590.  * gimp_image_merge_down:
  591.  * @image_ID: The image.
  592.  * @merge_layer_ID: The layer to merge down from.
  593.  * @merge_type: The type of merge.
  594.  *
  595.  * Merge the layer passed and the first visible layer below.
  596.  *
  597.  * This procedure combines the passed layer and the first visible layer
  598.  * below it using the specified merge type. A merge type of
  599.  * EXPAND_AS_NECESSARY expands the final layer to encompass the areas
  600.  * of the visible layers. A merge type of CLIP_TO_IMAGE clips the final
  601.  * layer to the extents of the image. A merge type of
  602.  * CLIP_TO_BOTTOM_LAYER clips the final layer to the size of the
  603.  * bottommost layer.
  604.  *
  605.  * Returns: The resulting layer.
  606.  */
  607. gint32
  608. gimp_image_merge_down (gint32        image_ID,
  609.                gint32        merge_layer_ID,
  610.                GimpMergeType merge_type)
  611. {
  612.   GimpParam *return_vals;
  613.   gint nreturn_vals;
  614.   gint32 layer_ID = -1;
  615.  
  616.   return_vals = gimp_run_procedure ("gimp_image_merge_down",
  617.                     &nreturn_vals,
  618.                     GIMP_PDB_IMAGE, image_ID,
  619.                     GIMP_PDB_LAYER, merge_layer_ID,
  620.                     GIMP_PDB_INT32, merge_type,
  621.                     GIMP_PDB_END);
  622.  
  623.   if (return_vals[0].data.d_status == GIMP_PDB_SUCCESS)
  624.     layer_ID = return_vals[1].data.d_layer;
  625.  
  626.   gimp_destroy_params (return_vals, nreturn_vals);
  627.  
  628.   return layer_ID;
  629. }
  630.  
  631. /**
  632.  * gimp_image_flatten:
  633.  * @image_ID: The image.
  634.  *
  635.  * Flatten all visible layers into a single layer. Discard all
  636.  * invisible layers.
  637.  *
  638.  * This procedure combines the visible layers in a manner analogous to
  639.  * merging with the CLIP_TO_IMAGE merge type. Non-visible layers are
  640.  * discarded, and the resulting image is stripped of its alpha channel.
  641.  *
  642.  * Returns: The resulting layer.
  643.  */
  644. gint32
  645. gimp_image_flatten (gint32 image_ID)
  646. {
  647.   GimpParam *return_vals;
  648.   gint nreturn_vals;
  649.   gint32 layer_ID = -1;
  650.  
  651.   return_vals = gimp_run_procedure ("gimp_image_flatten",
  652.                     &nreturn_vals,
  653.                     GIMP_PDB_IMAGE, image_ID,
  654.                     GIMP_PDB_END);
  655.  
  656.   if (return_vals[0].data.d_status == GIMP_PDB_SUCCESS)
  657.     layer_ID = return_vals[1].data.d_layer;
  658.  
  659.   gimp_destroy_params (return_vals, nreturn_vals);
  660.  
  661.   return layer_ID;
  662. }
  663.  
  664. /**
  665.  * gimp_image_add_layer:
  666.  * @image_ID: The image.
  667.  * @layer_ID: The layer.
  668.  * @position: The layer position.
  669.  *
  670.  * Add the specified layer to the image.
  671.  *
  672.  * This procedure adds the specified layer to the gimage at the given
  673.  * position. If the position is specified as -1, then the layer is
  674.  * inserted at the top of the layer stack. If the layer to be added has
  675.  * no alpha channel, it must be added at position 0. The layer type
  676.  * must be compatible with the image base type.
  677.  *
  678.  * Returns: TRUE on success.
  679.  */
  680. gboolean
  681. gimp_image_add_layer (gint32 image_ID,
  682.               gint32 layer_ID,
  683.               gint   position)
  684. {
  685.   GimpParam *return_vals;
  686.   gint nreturn_vals;
  687.   gboolean success = TRUE;
  688.  
  689.   return_vals = gimp_run_procedure ("gimp_image_add_layer",
  690.                     &nreturn_vals,
  691.                     GIMP_PDB_IMAGE, image_ID,
  692.                     GIMP_PDB_LAYER, layer_ID,
  693.                     GIMP_PDB_INT32, position,
  694.                     GIMP_PDB_END);
  695.  
  696.   success = return_vals[0].data.d_status == GIMP_PDB_SUCCESS;
  697.  
  698.   gimp_destroy_params (return_vals, nreturn_vals);
  699.  
  700.   return success;
  701. }
  702.  
  703. /**
  704.  * gimp_image_remove_layer:
  705.  * @image_ID: The image.
  706.  * @layer_ID: The layer.
  707.  *
  708.  * Remove the specified layer from the image.
  709.  *
  710.  * This procedure removes the specified layer from the image. If the
  711.  * layer doesn't exist, an error is returned. If there are no layers
  712.  * left in the image, this call will fail. If this layer is the last
  713.  * layer remaining, the image will become empty and have no active
  714.  * layer.
  715.  *
  716.  * Returns: TRUE on success.
  717.  */
  718. gboolean
  719. gimp_image_remove_layer (gint32 image_ID,
  720.              gint32 layer_ID)
  721. {
  722.   GimpParam *return_vals;
  723.   gint nreturn_vals;
  724.   gboolean success = TRUE;
  725.  
  726.   return_vals = gimp_run_procedure ("gimp_image_remove_layer",
  727.                     &nreturn_vals,
  728.                     GIMP_PDB_IMAGE, image_ID,
  729.                     GIMP_PDB_LAYER, layer_ID,
  730.                     GIMP_PDB_END);
  731.  
  732.   success = return_vals[0].data.d_status == GIMP_PDB_SUCCESS;
  733.  
  734.   gimp_destroy_params (return_vals, nreturn_vals);
  735.  
  736.   return success;
  737. }
  738.  
  739. /**
  740.  * gimp_image_add_layer_mask:
  741.  * @image_ID: The image.
  742.  * @layer_ID: The layer to receive the mask.
  743.  * @mask_ID: The mask to add to the layer.
  744.  *
  745.  * Add a layer mask to the specified layer.
  746.  *
  747.  * This procedure adds a layer mask to the specified layer. Layer masks
  748.  * serve as an additional alpha channel for a layer. This procedure
  749.  * will fail if a number of prerequisites aren't met. The layer cannot
  750.  * already have a layer mask. The specified mask must exist and have
  751.  * the same dimensions as the layer. Both the mask and the layer must
  752.  * have been created for use with the specified image.
  753.  *
  754.  * Returns: TRUE on success.
  755.  */
  756. gboolean
  757. gimp_image_add_layer_mask (gint32 image_ID,
  758.                gint32 layer_ID,
  759.                gint32 mask_ID)
  760. {
  761.   GimpParam *return_vals;
  762.   gint nreturn_vals;
  763.   gboolean success = TRUE;
  764.  
  765.   return_vals = gimp_run_procedure ("gimp_image_add_layer_mask",
  766.                     &nreturn_vals,
  767.                     GIMP_PDB_IMAGE, image_ID,
  768.                     GIMP_PDB_LAYER, layer_ID,
  769.                     GIMP_PDB_CHANNEL, mask_ID,
  770.                     GIMP_PDB_END);
  771.  
  772.   success = return_vals[0].data.d_status == GIMP_PDB_SUCCESS;
  773.  
  774.   gimp_destroy_params (return_vals, nreturn_vals);
  775.  
  776.   return success;
  777. }
  778.  
  779. /**
  780.  * gimp_image_remove_layer_mask:
  781.  * @image_ID: The image.
  782.  * @layer_ID: The layer from which to remove mask.
  783.  * @mode: Removal mode.
  784.  *
  785.  * Remove the specified layer mask from the layer.
  786.  *
  787.  * This procedure removes the specified layer mask from the layer. If
  788.  * the mask doesn't exist, an error is returned.
  789.  *
  790.  * Returns: TRUE on success.
  791.  */
  792. gboolean
  793. gimp_image_remove_layer_mask (gint32            image_ID,
  794.                   gint32            layer_ID,
  795.                   GimpMaskApplyMode mode)
  796. {
  797.   GimpParam *return_vals;
  798.   gint nreturn_vals;
  799.   gboolean success = TRUE;
  800.  
  801.   return_vals = gimp_run_procedure ("gimp_image_remove_layer_mask",
  802.                     &nreturn_vals,
  803.                     GIMP_PDB_IMAGE, image_ID,
  804.                     GIMP_PDB_LAYER, layer_ID,
  805.                     GIMP_PDB_INT32, mode,
  806.                     GIMP_PDB_END);
  807.  
  808.   success = return_vals[0].data.d_status == GIMP_PDB_SUCCESS;
  809.  
  810.   gimp_destroy_params (return_vals, nreturn_vals);
  811.  
  812.   return success;
  813. }
  814.  
  815. /**
  816.  * gimp_image_raise_channel:
  817.  * @image_ID: The image.
  818.  * @channel_ID: The channel to raise.
  819.  *
  820.  * Raise the specified channel in the image's channel stack
  821.  *
  822.  * This procedure raises the specified channel one step in the existing
  823.  * channel stack. It will not move the channel if there is no channel
  824.  * above it.
  825.  *
  826.  * Returns: TRUE on success.
  827.  */
  828. gboolean
  829. gimp_image_raise_channel (gint32 image_ID,
  830.               gint32 channel_ID)
  831. {
  832.   GimpParam *return_vals;
  833.   gint nreturn_vals;
  834.   gboolean success = TRUE;
  835.  
  836.   return_vals = gimp_run_procedure ("gimp_image_raise_channel",
  837.                     &nreturn_vals,
  838.                     GIMP_PDB_IMAGE, image_ID,
  839.                     GIMP_PDB_CHANNEL, channel_ID,
  840.                     GIMP_PDB_END);
  841.  
  842.   success = return_vals[0].data.d_status == GIMP_PDB_SUCCESS;
  843.  
  844.   gimp_destroy_params (return_vals, nreturn_vals);
  845.  
  846.   return success;
  847. }
  848.  
  849. /**
  850.  * gimp_image_lower_channel:
  851.  * @image_ID: The image.
  852.  * @layer_ID: The layer to lower.
  853.  *
  854.  * Lower the specified layer in the image's layer stack
  855.  *
  856.  * This procedure lowers the specified layer one step in the existing
  857.  * layer stack. It will not move the layer if there is no layer below
  858.  * it, or the layer has no alpha channel.
  859.  *
  860.  * Returns: TRUE on success.
  861.  */
  862. gboolean
  863. gimp_image_lower_channel (gint32 image_ID,
  864.               gint32 layer_ID)
  865. {
  866.   GimpParam *return_vals;
  867.   gint nreturn_vals;
  868.   gboolean success = TRUE;
  869.  
  870.   return_vals = gimp_run_procedure ("gimp_image_lower_channel",
  871.                     &nreturn_vals,
  872.                     GIMP_PDB_IMAGE, image_ID,
  873.                     GIMP_PDB_LAYER, layer_ID,
  874.                     GIMP_PDB_END);
  875.  
  876.   success = return_vals[0].data.d_status == GIMP_PDB_SUCCESS;
  877.  
  878.   gimp_destroy_params (return_vals, nreturn_vals);
  879.  
  880.   return success;
  881. }
  882.  
  883. /**
  884.  * gimp_image_add_channel:
  885.  * @image_ID: The image.
  886.  * @channel_ID: The channel.
  887.  * @position: The channel position.
  888.  *
  889.  * Add the specified channel to the image.
  890.  *
  891.  * This procedure adds the specified channel to the image. The position
  892.  * channel is not currently used, so the channel is always inserted at
  893.  * the top of the channel stack.
  894.  *
  895.  * Returns: TRUE on success.
  896.  */
  897. gboolean
  898. gimp_image_add_channel (gint32 image_ID,
  899.             gint32 channel_ID,
  900.             gint   position)
  901. {
  902.   GimpParam *return_vals;
  903.   gint nreturn_vals;
  904.   gboolean success = TRUE;
  905.  
  906.   return_vals = gimp_run_procedure ("gimp_image_add_channel",
  907.                     &nreturn_vals,
  908.                     GIMP_PDB_IMAGE, image_ID,
  909.                     GIMP_PDB_CHANNEL, channel_ID,
  910.                     GIMP_PDB_INT32, position,
  911.                     GIMP_PDB_END);
  912.  
  913.   success = return_vals[0].data.d_status == GIMP_PDB_SUCCESS;
  914.  
  915.   gimp_destroy_params (return_vals, nreturn_vals);
  916.  
  917.   return success;
  918. }
  919.  
  920. /**
  921.  * gimp_image_remove_channel:
  922.  * @image_ID: The image.
  923.  * @channel_ID: The channel.
  924.  *
  925.  * Remove the specified channel from the image.
  926.  *
  927.  * This procedure removes the specified channel from the image. If the
  928.  * channel doesn't exist, an error is returned.
  929.  *
  930.  * Returns: TRUE on success.
  931.  */
  932. gboolean
  933. gimp_image_remove_channel (gint32 image_ID,
  934.                gint32 channel_ID)
  935. {
  936.   GimpParam *return_vals;
  937.   gint nreturn_vals;
  938.   gboolean success = TRUE;
  939.  
  940.   return_vals = gimp_run_procedure ("gimp_image_remove_channel",
  941.                     &nreturn_vals,
  942.                     GIMP_PDB_IMAGE, image_ID,
  943.                     GIMP_PDB_CHANNEL, channel_ID,
  944.                     GIMP_PDB_END);
  945.  
  946.   success = return_vals[0].data.d_status == GIMP_PDB_SUCCESS;
  947.  
  948.   gimp_destroy_params (return_vals, nreturn_vals);
  949.  
  950.   return success;
  951. }
  952.  
  953. /**
  954.  * gimp_image_active_drawable:
  955.  * @image_ID: The image.
  956.  *
  957.  * Get the image's active drawable
  958.  *
  959.  * This procedure returns the ID of the image's active drawable. This
  960.  * can be either a layer, a channel, or a layer mask. The active
  961.  * drawable is specified by the active image channel. If that is -1,
  962.  * then by the active image layer. If the active image layer has a
  963.  * layer mask and the layer mask is in edit mode, then the layer mask
  964.  * is the active drawable.
  965.  *
  966.  * Returns: The active drawable.
  967.  */
  968. gint32
  969. gimp_image_active_drawable (gint32 image_ID)
  970. {
  971.   GimpParam *return_vals;
  972.   gint nreturn_vals;
  973.   gint32 drawable_ID = -1;
  974.  
  975.   return_vals = gimp_run_procedure ("gimp_image_active_drawable",
  976.                     &nreturn_vals,
  977.                     GIMP_PDB_IMAGE, image_ID,
  978.                     GIMP_PDB_END);
  979.  
  980.   if (return_vals[0].data.d_status == GIMP_PDB_SUCCESS)
  981.     drawable_ID = return_vals[1].data.d_drawable;
  982.  
  983.   gimp_destroy_params (return_vals, nreturn_vals);
  984.  
  985.   return drawable_ID;
  986. }
  987.  
  988. /**
  989.  * gimp_image_base_type:
  990.  * @image_ID: The image.
  991.  *
  992.  * Get the base type of the image.
  993.  *
  994.  * This procedure returns the image's base type. Layers in the image
  995.  * must be of this subtype, but can have an optional alpha channel.
  996.  *
  997.  * Returns: The image's base type.
  998.  */
  999. GimpImageBaseType
  1000. gimp_image_base_type (gint32 image_ID)
  1001. {
  1002.   GimpParam *return_vals;
  1003.   gint nreturn_vals;
  1004.   GimpImageBaseType base_type = 0;
  1005.  
  1006.   return_vals = gimp_run_procedure ("gimp_image_base_type",
  1007.                     &nreturn_vals,
  1008.                     GIMP_PDB_IMAGE, image_ID,
  1009.                     GIMP_PDB_END);
  1010.  
  1011.   if (return_vals[0].data.d_status == GIMP_PDB_SUCCESS)
  1012.     base_type = return_vals[1].data.d_int32;
  1013.  
  1014.   gimp_destroy_params (return_vals, nreturn_vals);
  1015.  
  1016.   return base_type;
  1017. }
  1018.  
  1019. /**
  1020.  * _gimp_image_get_cmap:
  1021.  * @image_ID: The image.
  1022.  * @num_bytes: Number of bytes in the colormap array.
  1023.  *
  1024.  * Returns the image's colormap
  1025.  *
  1026.  * This procedure returns an actual pointer to the image's colormap, as
  1027.  * well as the number of bytes contained in the colormap. The actual
  1028.  * number of colors in the transmitted colormap will be \"num_bytes\" /
  1029.  * 3. If the image is not of base type INDEXED, this pointer will be
  1030.  * NULL.
  1031.  *
  1032.  * Returns: The image's colormap.
  1033.  */
  1034. guint8 *
  1035. _gimp_image_get_cmap (gint32  image_ID,
  1036.               gint   *num_bytes)
  1037. {
  1038.   GimpParam *return_vals;
  1039.   gint nreturn_vals;
  1040.   guint8 *cmap = NULL;
  1041.  
  1042.   return_vals = gimp_run_procedure ("gimp_image_get_cmap",
  1043.                     &nreturn_vals,
  1044.                     GIMP_PDB_IMAGE, image_ID,
  1045.                     GIMP_PDB_END);
  1046.  
  1047.   *num_bytes = 0;
  1048.  
  1049.   if (return_vals[0].data.d_status == GIMP_PDB_SUCCESS)
  1050.     {
  1051.       *num_bytes = return_vals[1].data.d_int32;
  1052.       cmap = g_new (guint8, *num_bytes);
  1053.       memcpy (cmap, return_vals[2].data.d_int8array,
  1054.           *num_bytes * sizeof (guint8));
  1055.     }
  1056.  
  1057.   gimp_destroy_params (return_vals, nreturn_vals);
  1058.  
  1059.   return cmap;
  1060. }
  1061.  
  1062. /**
  1063.  * _gimp_image_set_cmap:
  1064.  * @image_ID: The image.
  1065.  * @num_bytes: Number of bytes in the colormap array.
  1066.  * @cmap: The new colormap values.
  1067.  *
  1068.  * Sets the entries in the image's colormap.
  1069.  *
  1070.  * This procedure sets the entries in the specified image's colormap.
  1071.  * The number of entries is specified by the \"num_bytes\" parameter
  1072.  * and corresponds to the number of INT8 triples that must be contained
  1073.  * in the \"cmap\" array. The actual number of colors in the
  1074.  * transmitted colormap is \"num_bytes\" / 3.
  1075.  *
  1076.  * Returns: TRUE on success.
  1077.  */
  1078. gboolean
  1079. _gimp_image_set_cmap (gint32  image_ID,
  1080.               gint    num_bytes,
  1081.               guint8 *cmap)
  1082. {
  1083.   GimpParam *return_vals;
  1084.   gint nreturn_vals;
  1085.   gboolean success = TRUE;
  1086.  
  1087.   return_vals = gimp_run_procedure ("gimp_image_set_cmap",
  1088.                     &nreturn_vals,
  1089.                     GIMP_PDB_IMAGE, image_ID,
  1090.                     GIMP_PDB_INT32, num_bytes,
  1091.                     GIMP_PDB_INT8ARRAY, cmap,
  1092.                     GIMP_PDB_END);
  1093.  
  1094.   success = return_vals[0].data.d_status == GIMP_PDB_SUCCESS;
  1095.  
  1096.   gimp_destroy_params (return_vals, nreturn_vals);
  1097.  
  1098.   return success;
  1099. }
  1100.  
  1101. /**
  1102.  * gimp_image_undo_is_enabled:
  1103.  * @image_ID: The image.
  1104.  *
  1105.  * Check if the image's undo stack is enabled.
  1106.  *
  1107.  * This procedure checks if the image's undo stack is currently enabled
  1108.  * or disabled. This is useful when several plugins or scripts call
  1109.  * each other and want to check if their caller has already used
  1110.  * 'gimp_image_undo_disable' or 'gimp_image_undo_freeze'.
  1111.  *
  1112.  * Returns: True if undo is enabled for this image.
  1113.  */
  1114. gboolean
  1115. gimp_image_undo_is_enabled (gint32 image_ID)
  1116. {
  1117.   GimpParam *return_vals;
  1118.   gint nreturn_vals;
  1119.   gboolean enabled = FALSE;
  1120.  
  1121.   return_vals = gimp_run_procedure ("gimp_image_undo_is_enabled",
  1122.                     &nreturn_vals,
  1123.                     GIMP_PDB_IMAGE, image_ID,
  1124.                     GIMP_PDB_END);
  1125.  
  1126.   if (return_vals[0].data.d_status == GIMP_PDB_SUCCESS)
  1127.     enabled = return_vals[1].data.d_int32;
  1128.  
  1129.   gimp_destroy_params (return_vals, nreturn_vals);
  1130.  
  1131.   return enabled;
  1132. }
  1133.  
  1134. /**
  1135.  * gimp_image_undo_enable:
  1136.  * @image_ID: The image.
  1137.  *
  1138.  * Enable the image's undo stack.
  1139.  *
  1140.  * This procedure enables the image's undo stack, allowing subsequent
  1141.  * operations to store their undo steps. This is generally called in
  1142.  * conjunction with 'gimp_image_undo_disable' to temporarily disable an
  1143.  * image undo stack.
  1144.  *
  1145.  * Returns: True if the image undo has been enabled.
  1146.  */
  1147. gboolean
  1148. gimp_image_undo_enable (gint32 image_ID)
  1149. {
  1150.   GimpParam *return_vals;
  1151.   gint nreturn_vals;
  1152.   gboolean enabled = FALSE;
  1153.  
  1154.   return_vals = gimp_run_procedure ("gimp_image_undo_enable",
  1155.                     &nreturn_vals,
  1156.                     GIMP_PDB_IMAGE, image_ID,
  1157.                     GIMP_PDB_END);
  1158.  
  1159.   if (return_vals[0].data.d_status == GIMP_PDB_SUCCESS)
  1160.     enabled = return_vals[1].data.d_int32;
  1161.  
  1162.   gimp_destroy_params (return_vals, nreturn_vals);
  1163.  
  1164.   return enabled;
  1165. }
  1166.  
  1167. /**
  1168.  * gimp_image_undo_disable:
  1169.  * @image_ID: The image.
  1170.  *
  1171.  * Disable the image's undo stack.
  1172.  *
  1173.  * This procedure disables the image's undo stack, allowing subsequent
  1174.  * operations to ignore their undo steps. This is generally called in
  1175.  * conjunction with 'gimp_image_undo_enable' to temporarily disable an
  1176.  * image undo stack. This is advantageous because saving undo steps can
  1177.  * be time and memory intensive.
  1178.  *
  1179.  * Returns: True if the image undo has been disabled.
  1180.  */
  1181. gboolean
  1182. gimp_image_undo_disable (gint32 image_ID)
  1183. {
  1184.   GimpParam *return_vals;
  1185.   gint nreturn_vals;
  1186.   gboolean disabled = FALSE;
  1187.  
  1188.   return_vals = gimp_run_procedure ("gimp_image_undo_disable",
  1189.                     &nreturn_vals,
  1190.                     GIMP_PDB_IMAGE, image_ID,
  1191.                     GIMP_PDB_END);
  1192.  
  1193.   if (return_vals[0].data.d_status == GIMP_PDB_SUCCESS)
  1194.     disabled = return_vals[1].data.d_int32;
  1195.  
  1196.   gimp_destroy_params (return_vals, nreturn_vals);
  1197.  
  1198.   return disabled;
  1199. }
  1200.  
  1201. /**
  1202.  * gimp_image_undo_freeze:
  1203.  * @image_ID: The image.
  1204.  *
  1205.  * Freeze the image's undo stack.
  1206.  *
  1207.  * This procedure freezes the image's undo stack, allowing subsequent
  1208.  * operations to ignore their undo steps. This is generally called in
  1209.  * conjunction with 'gimp_image_undo_thaw' to temporarily disable an
  1210.  * image undo stack. This is advantageous because saving undo steps can
  1211.  * be time and memory intensive. 'gimp_image_undo_{freeze,thaw}' and
  1212.  * 'gimp_image_undo_{disable,enable}' differ in that the former does
  1213.  * not free up all undo steps when undo is thawed, so is more suited to
  1214.  * interactive in-situ previews. It is important in this case that the
  1215.  * image is back to the same state it was frozen in before thawing,
  1216.  * else 'undo' behaviour is undefined.
  1217.  *
  1218.  * Returns: True if the image undo has been frozen.
  1219.  */
  1220. gboolean
  1221. gimp_image_undo_freeze (gint32 image_ID)
  1222. {
  1223.   GimpParam *return_vals;
  1224.   gint nreturn_vals;
  1225.   gboolean frozen = FALSE;
  1226.  
  1227.   return_vals = gimp_run_procedure ("gimp_image_undo_freeze",
  1228.                     &nreturn_vals,
  1229.                     GIMP_PDB_IMAGE, image_ID,
  1230.                     GIMP_PDB_END);
  1231.  
  1232.   if (return_vals[0].data.d_status == GIMP_PDB_SUCCESS)
  1233.     frozen = return_vals[1].data.d_int32;
  1234.  
  1235.   gimp_destroy_params (return_vals, nreturn_vals);
  1236.  
  1237.   return frozen;
  1238. }
  1239.  
  1240. /**
  1241.  * gimp_image_undo_thaw:
  1242.  * @image_ID: The image.
  1243.  *
  1244.  * Thaw the image's undo stack.
  1245.  *
  1246.  * This procedure thaws the image's undo stack, allowing subsequent
  1247.  * operations to store their undo steps. This is generally called in
  1248.  * conjunction with 'gimp_image_undo_freeze' to temporarily freeze an
  1249.  * image undo stack. 'gimp_image_undo_thaw' does NOT free the undo
  1250.  * stack as 'gimp_image_undo_enable' does, so is suited for situations
  1251.  * where one wishes to leave the undo stack in the same state in which
  1252.  * one found it despite non-destructively playing with the image in the
  1253.  * meantime. An example would be in-situ plugin previews. Balancing
  1254.  * freezes and thaws and ensuring image consistancy is the
  1255.  * responsibility of the caller.
  1256.  *
  1257.  * Returns: True if the image undo has been thawed.
  1258.  */
  1259. gboolean
  1260. gimp_image_undo_thaw (gint32 image_ID)
  1261. {
  1262.   GimpParam *return_vals;
  1263.   gint nreturn_vals;
  1264.   gboolean thawed = FALSE;
  1265.  
  1266.   return_vals = gimp_run_procedure ("gimp_image_undo_thaw",
  1267.                     &nreturn_vals,
  1268.                     GIMP_PDB_IMAGE, image_ID,
  1269.                     GIMP_PDB_END);
  1270.  
  1271.   if (return_vals[0].data.d_status == GIMP_PDB_SUCCESS)
  1272.     thawed = return_vals[1].data.d_int32;
  1273.  
  1274.   gimp_destroy_params (return_vals, nreturn_vals);
  1275.  
  1276.   return thawed;
  1277. }
  1278.  
  1279. /**
  1280.  * gimp_image_clean_all:
  1281.  * @image_ID: The image.
  1282.  *
  1283.  * Set the image dirty count to 0.
  1284.  *
  1285.  * This procedure sets the specified image's dirty count to 0, allowing
  1286.  * operations to occur without having a 'dirtied' image. This is
  1287.  * especially useful for creating and loading images which should not
  1288.  * initially be considered dirty, even though layers must be created,
  1289.  * filled, and installed in the image.
  1290.  *
  1291.  * Returns: TRUE on success.
  1292.  */
  1293. gboolean
  1294. gimp_image_clean_all (gint32 image_ID)
  1295. {
  1296.   GimpParam *return_vals;
  1297.   gint nreturn_vals;
  1298.   gboolean success = TRUE;
  1299.  
  1300.   return_vals = gimp_run_procedure ("gimp_image_clean_all",
  1301.                     &nreturn_vals,
  1302.                     GIMP_PDB_IMAGE, image_ID,
  1303.                     GIMP_PDB_END);
  1304.  
  1305.   success = return_vals[0].data.d_status == GIMP_PDB_SUCCESS;
  1306.  
  1307.   gimp_destroy_params (return_vals, nreturn_vals);
  1308.  
  1309.   return success;
  1310. }
  1311.  
  1312. /**
  1313.  * gimp_image_floating_selection:
  1314.  * @image_ID: The image.
  1315.  *
  1316.  * Return the floating selection of the image.
  1317.  *
  1318.  * This procedure returns the image's floating_sel, if it exists. If it
  1319.  * doesn't exist, -1 is returned as the layer ID.
  1320.  *
  1321.  * Returns: The image's floating selection.
  1322.  */
  1323. gint32
  1324. gimp_image_floating_selection (gint32 image_ID)
  1325. {
  1326.   GimpParam *return_vals;
  1327.   gint nreturn_vals;
  1328.   gint32 floating_sel_ID = -1;
  1329.  
  1330.   return_vals = gimp_run_procedure ("gimp_image_floating_selection",
  1331.                     &nreturn_vals,
  1332.                     GIMP_PDB_IMAGE, image_ID,
  1333.                     GIMP_PDB_END);
  1334.  
  1335.   if (return_vals[0].data.d_status == GIMP_PDB_SUCCESS)
  1336.     floating_sel_ID = return_vals[1].data.d_layer;
  1337.  
  1338.   gimp_destroy_params (return_vals, nreturn_vals);
  1339.  
  1340.   return floating_sel_ID;
  1341. }
  1342.  
  1343. /**
  1344.  * gimp_image_floating_sel_attached_to:
  1345.  * @image_ID: The image.
  1346.  *
  1347.  * Return the drawable the floating selection is attached to.
  1348.  *
  1349.  * This procedure returns the drawable the image's floating selection
  1350.  * is attached to, if it exists. If it doesn't exist, -1 is returned as
  1351.  * the drawable ID.
  1352.  *
  1353.  * Returns: The drawable the floating selection is attached to.
  1354.  */
  1355. gint32
  1356. gimp_image_floating_sel_attached_to (gint32 image_ID)
  1357. {
  1358.   GimpParam *return_vals;
  1359.   gint nreturn_vals;
  1360.   gint32 drawable_ID = -1;
  1361.  
  1362.   return_vals = gimp_run_procedure ("gimp_image_floating_sel_attached_to",
  1363.                     &nreturn_vals,
  1364.                     GIMP_PDB_IMAGE, image_ID,
  1365.                     GIMP_PDB_END);
  1366.  
  1367.   if (return_vals[0].data.d_status == GIMP_PDB_SUCCESS)
  1368.     drawable_ID = return_vals[1].data.d_drawable;
  1369.  
  1370.   gimp_destroy_params (return_vals, nreturn_vals);
  1371.  
  1372.   return drawable_ID;
  1373. }
  1374.  
  1375. /**
  1376.  * _gimp_image_thumbnail:
  1377.  * @image_ID: The image.
  1378.  * @width: The thumbnail width.
  1379.  * @height: The thumbnail height.
  1380.  * @ret_width: The previews width.
  1381.  * @ret_height: The previews height.
  1382.  * @bpp: The previews bpp.
  1383.  * @thumbnail_data_count: The number of bytes in thumbnail data.
  1384.  * @thumbnail_data: The thumbnail data.
  1385.  *
  1386.  * Get a thumbnail of an image.
  1387.  *
  1388.  * This function gets data from which a thumbnail of an image preview
  1389.  * can be created. Maximum x or y dimension is 128 pixels. The pixels
  1390.  * are returned in the RGB[A] format. The bpp return value gives the
  1391.  * number of bits per pixel in the image. If the image has an alpha
  1392.  * channel, it is also returned.
  1393.  *
  1394.  * Returns: TRUE on success.
  1395.  */
  1396. gboolean
  1397. _gimp_image_thumbnail (gint32   image_ID,
  1398.                gint     width,
  1399.                gint     height,
  1400.                gint    *ret_width,
  1401.                gint    *ret_height,
  1402.                gint    *bpp,
  1403.                gint    *thumbnail_data_count,
  1404.                guint8 **thumbnail_data)
  1405. {
  1406.   GimpParam *return_vals;
  1407.   gint nreturn_vals;
  1408.   gboolean success = TRUE;
  1409.  
  1410.   return_vals = gimp_run_procedure ("gimp_image_thumbnail",
  1411.                     &nreturn_vals,
  1412.                     GIMP_PDB_IMAGE, image_ID,
  1413.                     GIMP_PDB_INT32, width,
  1414.                     GIMP_PDB_INT32, height,
  1415.                     GIMP_PDB_END);
  1416.  
  1417.   *ret_width = 0;
  1418.   *ret_height = 0;
  1419.   *bpp = 0;
  1420.   *thumbnail_data_count = 0;
  1421.   *thumbnail_data = NULL;
  1422.  
  1423.   success = return_vals[0].data.d_status == GIMP_PDB_SUCCESS;
  1424.  
  1425.   if (success)
  1426.     {
  1427.       *ret_width = return_vals[1].data.d_int32;
  1428.       *ret_height = return_vals[2].data.d_int32;
  1429.       *bpp = return_vals[3].data.d_int32;
  1430.       *thumbnail_data_count = return_vals[4].data.d_int32;
  1431.       *thumbnail_data = g_new (guint8, *thumbnail_data_count);
  1432.       memcpy (*thumbnail_data, return_vals[5].data.d_int8array,
  1433.           *thumbnail_data_count * sizeof (guint8));
  1434.     }
  1435.  
  1436.   gimp_destroy_params (return_vals, nreturn_vals);
  1437.  
  1438.   return success;
  1439. }
  1440.  
  1441. /**
  1442.  * gimp_image_set_tattoo_state:
  1443.  * @image_ID: The image.
  1444.  * @tattoo: The new tattoo state of the image.
  1445.  *
  1446.  * Set the tattoo state associated with the image.
  1447.  *
  1448.  * This procedure sets the tattoo state of the image. Use only by
  1449.  * save/load plugins that wish to preserve an images tattoo state.
  1450.  * Using this function at other times will produce unexpected results.
  1451.  * A full check of uniqueness of states in layers, channels and paths
  1452.  * will be performed by this procedure and a execution failure will be
  1453.  * returned if this fails. A failure will also be returned if the new
  1454.  * tattoo state value is less than the maximum tattoo value from all of
  1455.  * the tattoos from the paths,layers and channels. After the image data
  1456.  * has been loaded and all the tattoos have been set then this is the
  1457.  * last procedure that should be called. If effectively does a status
  1458.  * check on the tattoo values that have been set to make sure that all
  1459.  * is OK.
  1460.  *
  1461.  * Returns: TRUE on success.
  1462.  */
  1463. gboolean
  1464. gimp_image_set_tattoo_state (gint32 image_ID,
  1465.                  gint   tattoo)
  1466. {
  1467.   GimpParam *return_vals;
  1468.   gint nreturn_vals;
  1469.   gboolean success = TRUE;
  1470.  
  1471.   return_vals = gimp_run_procedure ("gimp_image_set_tattoo_state",
  1472.                     &nreturn_vals,
  1473.                     GIMP_PDB_IMAGE, image_ID,
  1474.                     GIMP_PDB_INT32, tattoo,
  1475.                     GIMP_PDB_END);
  1476.  
  1477.   success = return_vals[0].data.d_status == GIMP_PDB_SUCCESS;
  1478.  
  1479.   gimp_destroy_params (return_vals, nreturn_vals);
  1480.  
  1481.   return success;
  1482. }
  1483.  
  1484. /**
  1485.  * gimp_image_get_tattoo_state:
  1486.  * @image_ID: The image.
  1487.  *
  1488.  * Returns the tattoo state associated with the image.
  1489.  *
  1490.  * This procedure returns the tattoo state of the image. Use only by
  1491.  * save/load plugins that wish to preserve an images tattoo state.
  1492.  * Using this function at other times will produce unexpected results.
  1493.  *
  1494.  * Returns: The tattoo state associated with the image.
  1495.  */
  1496. gint
  1497. gimp_image_get_tattoo_state (gint32 image_ID)
  1498. {
  1499.   GimpParam *return_vals;
  1500.   gint nreturn_vals;
  1501.   gint tattoo = 0;
  1502.  
  1503.   return_vals = gimp_run_procedure ("gimp_image_get_tattoo_state",
  1504.                     &nreturn_vals,
  1505.                     GIMP_PDB_IMAGE, image_ID,
  1506.                     GIMP_PDB_END);
  1507.  
  1508.   if (return_vals[0].data.d_status == GIMP_PDB_SUCCESS)
  1509.     tattoo = return_vals[1].data.d_int32;
  1510.  
  1511.   gimp_destroy_params (return_vals, nreturn_vals);
  1512.  
  1513.   return tattoo;
  1514. }
  1515.  
  1516. /**
  1517.  * gimp_image_width:
  1518.  * @image_ID: The image.
  1519.  *
  1520.  * Return the width of the image
  1521.  *
  1522.  * This procedure returns the image's width. This value is independent
  1523.  * of any of the layers in this image. This is the \"canvas\" width.
  1524.  *
  1525.  * Returns: The image's width.
  1526.  */
  1527. gint
  1528. gimp_image_width (gint32 image_ID)
  1529. {
  1530.   GimpParam *return_vals;
  1531.   gint nreturn_vals;
  1532.   gint width = 0;
  1533.  
  1534.   return_vals = gimp_run_procedure ("gimp_image_width",
  1535.                     &nreturn_vals,
  1536.                     GIMP_PDB_IMAGE, image_ID,
  1537.                     GIMP_PDB_END);
  1538.  
  1539.   if (return_vals[0].data.d_status == GIMP_PDB_SUCCESS)
  1540.     width = return_vals[1].data.d_int32;
  1541.  
  1542.   gimp_destroy_params (return_vals, nreturn_vals);
  1543.  
  1544.   return width;
  1545. }
  1546.  
  1547. /**
  1548.  * gimp_image_height:
  1549.  * @image_ID: The image.
  1550.  *
  1551.  * Return the height of the image
  1552.  *
  1553.  * This procedure returns the image's height. This value is independent
  1554.  * of any of the layers in this image. This is the \"canvas\" height.
  1555.  *
  1556.  * Returns: The image's height.
  1557.  */
  1558. gint
  1559. gimp_image_height (gint32 image_ID)
  1560. {
  1561.   GimpParam *return_vals;
  1562.   gint nreturn_vals;
  1563.   gint height = 0;
  1564.  
  1565.   return_vals = gimp_run_procedure ("gimp_image_height",
  1566.                     &nreturn_vals,
  1567.                     GIMP_PDB_IMAGE, image_ID,
  1568.                     GIMP_PDB_END);
  1569.  
  1570.   if (return_vals[0].data.d_status == GIMP_PDB_SUCCESS)
  1571.     height = return_vals[1].data.d_int32;
  1572.  
  1573.   gimp_destroy_params (return_vals, nreturn_vals);
  1574.  
  1575.   return height;
  1576. }
  1577.  
  1578. /**
  1579.  * gimp_image_get_active_layer:
  1580.  * @image_ID: The image.
  1581.  *
  1582.  * Returns the specified image's active layer.
  1583.  *
  1584.  * If there is an active layer, its ID will be returned, otherwise, -1.
  1585.  * If a channel is currently active, then no layer will be. If a layer
  1586.  * mask is active, then this will return the associated layer.
  1587.  *
  1588.  * Returns: The active layer.
  1589.  */
  1590. gint32
  1591. gimp_image_get_active_layer (gint32 image_ID)
  1592. {
  1593.   GimpParam *return_vals;
  1594.   gint nreturn_vals;
  1595.   gint32 active_layer_ID = -1;
  1596.  
  1597.   return_vals = gimp_run_procedure ("gimp_image_get_active_layer",
  1598.                     &nreturn_vals,
  1599.                     GIMP_PDB_IMAGE, image_ID,
  1600.                     GIMP_PDB_END);
  1601.  
  1602.   if (return_vals[0].data.d_status == GIMP_PDB_SUCCESS)
  1603.     active_layer_ID = return_vals[1].data.d_layer;
  1604.  
  1605.   gimp_destroy_params (return_vals, nreturn_vals);
  1606.  
  1607.   return active_layer_ID;
  1608. }
  1609.  
  1610. /**
  1611.  * gimp_image_set_active_layer:
  1612.  * @image_ID: The image.
  1613.  * @active_layer_ID: The new image active layer.
  1614.  *
  1615.  * Sets the specified image's active layer.
  1616.  *
  1617.  * If the layer exists, it is set as the active layer in the image. Any
  1618.  * previous active layer or channel is set to inactive. An exception is
  1619.  * a previously existing floating selection, in which case this
  1620.  * procedure will return an execution error.
  1621.  *
  1622.  * Returns: TRUE on success.
  1623.  */
  1624. gboolean
  1625. gimp_image_set_active_layer (gint32 image_ID,
  1626.                  gint32 active_layer_ID)
  1627. {
  1628.   GimpParam *return_vals;
  1629.   gint nreturn_vals;
  1630.   gboolean success = TRUE;
  1631.  
  1632.   return_vals = gimp_run_procedure ("gimp_image_set_active_layer",
  1633.                     &nreturn_vals,
  1634.                     GIMP_PDB_IMAGE, image_ID,
  1635.                     GIMP_PDB_LAYER, active_layer_ID,
  1636.                     GIMP_PDB_END);
  1637.  
  1638.   success = return_vals[0].data.d_status == GIMP_PDB_SUCCESS;
  1639.  
  1640.   gimp_destroy_params (return_vals, nreturn_vals);
  1641.  
  1642.   return success;
  1643. }
  1644.  
  1645. /**
  1646.  * gimp_image_get_active_channel:
  1647.  * @image_ID: The image.
  1648.  *
  1649.  * Returns the specified image's active channel.
  1650.  *
  1651.  * If there is an active channel, this will return the channel ID,
  1652.  * otherwise, -1.
  1653.  *
  1654.  * Returns: The active channel.
  1655.  */
  1656. gint32
  1657. gimp_image_get_active_channel (gint32 image_ID)
  1658. {
  1659.   GimpParam *return_vals;
  1660.   gint nreturn_vals;
  1661.   gint32 active_channel_ID = -1;
  1662.  
  1663.   return_vals = gimp_run_procedure ("gimp_image_get_active_channel",
  1664.                     &nreturn_vals,
  1665.                     GIMP_PDB_IMAGE, image_ID,
  1666.                     GIMP_PDB_END);
  1667.  
  1668.   if (return_vals[0].data.d_status == GIMP_PDB_SUCCESS)
  1669.     active_channel_ID = return_vals[1].data.d_channel;
  1670.  
  1671.   gimp_destroy_params (return_vals, nreturn_vals);
  1672.  
  1673.   return active_channel_ID;
  1674. }
  1675.  
  1676. /**
  1677.  * gimp_image_set_active_channel:
  1678.  * @image_ID: The image.
  1679.  * @active_channel_ID: The new image active channel.
  1680.  *
  1681.  * Sets the specified image's active channel.
  1682.  *
  1683.  * If the channel exists, it is set as the active channel in the image.
  1684.  * Any previous active channel or channel is set to inactive. An
  1685.  * exception is a previously existing floating selection, in which case
  1686.  * this procedure will return an execution error.
  1687.  *
  1688.  * Returns: TRUE on success.
  1689.  */
  1690. gboolean
  1691. gimp_image_set_active_channel (gint32 image_ID,
  1692.                    gint32 active_channel_ID)
  1693. {
  1694.   GimpParam *return_vals;
  1695.   gint nreturn_vals;
  1696.   gboolean success = TRUE;
  1697.  
  1698.   return_vals = gimp_run_procedure ("gimp_image_set_active_channel",
  1699.                     &nreturn_vals,
  1700.                     GIMP_PDB_IMAGE, image_ID,
  1701.                     GIMP_PDB_CHANNEL, active_channel_ID,
  1702.                     GIMP_PDB_END);
  1703.  
  1704.   success = return_vals[0].data.d_status == GIMP_PDB_SUCCESS;
  1705.  
  1706.   gimp_destroy_params (return_vals, nreturn_vals);
  1707.  
  1708.   return success;
  1709. }
  1710.  
  1711. /**
  1712.  * gimp_image_get_selection:
  1713.  * @image_ID: The image.
  1714.  *
  1715.  * Returns the specified image's selection.
  1716.  *
  1717.  * This will always return a valid ID for a selection -- which is
  1718.  * represented as a channel internally.
  1719.  *
  1720.  * Returns: The selection channel.
  1721.  */
  1722. gint32
  1723. gimp_image_get_selection (gint32 image_ID)
  1724. {
  1725.   GimpParam *return_vals;
  1726.   gint nreturn_vals;
  1727.   gint32 selection_ID = -1;
  1728.  
  1729.   return_vals = gimp_run_procedure ("gimp_image_get_selection",
  1730.                     &nreturn_vals,
  1731.                     GIMP_PDB_IMAGE, image_ID,
  1732.                     GIMP_PDB_END);
  1733.  
  1734.   if (return_vals[0].data.d_status == GIMP_PDB_SUCCESS)
  1735.     selection_ID = return_vals[1].data.d_selection;
  1736.  
  1737.   gimp_destroy_params (return_vals, nreturn_vals);
  1738.  
  1739.   return selection_ID;
  1740. }
  1741.  
  1742. /**
  1743.  * gimp_image_get_component_active:
  1744.  * @image_ID: The image.
  1745.  * @component: The image component.
  1746.  *
  1747.  * Returns if the specified image's image component is active.
  1748.  *
  1749.  * This procedure returns if the specified image's image component
  1750.  * (i.e. Red, Green, Blue intensity channels in an RGB image) is active
  1751.  * or inactive -- whether or not it can be modified. If the specified
  1752.  * component is not valid for the image type, an error is returned.
  1753.  *
  1754.  * Returns: Component is active.
  1755.  */
  1756. gboolean
  1757. gimp_image_get_component_active (gint32          image_ID,
  1758.                  GimpChannelType component)
  1759. {
  1760.   GimpParam *return_vals;
  1761.   gint nreturn_vals;
  1762.   gboolean active = FALSE;
  1763.  
  1764.   return_vals = gimp_run_procedure ("gimp_image_get_component_active",
  1765.                     &nreturn_vals,
  1766.                     GIMP_PDB_IMAGE, image_ID,
  1767.                     GIMP_PDB_INT32, component,
  1768.                     GIMP_PDB_END);
  1769.  
  1770.   if (return_vals[0].data.d_status == GIMP_PDB_SUCCESS)
  1771.     active = return_vals[1].data.d_int32;
  1772.  
  1773.   gimp_destroy_params (return_vals, nreturn_vals);
  1774.  
  1775.   return active;
  1776. }
  1777.  
  1778. /**
  1779.  * gimp_image_set_component_active:
  1780.  * @image_ID: The image.
  1781.  * @component: The image component.
  1782.  * @active: Component is active.
  1783.  *
  1784.  * Sets if the specified image's image component is active.
  1785.  *
  1786.  * This procedure sets if the specified image's image component (i.e.
  1787.  * Red, Green, Blue intensity channels in an RGB image) is active or
  1788.  * inactive -- whether or not it can be modified. If the specified
  1789.  * component is not valid for the image type, an error is returned.
  1790.  *
  1791.  * Returns: TRUE on success.
  1792.  */
  1793. gboolean
  1794. gimp_image_set_component_active (gint32          image_ID,
  1795.                  GimpChannelType component,
  1796.                  gboolean        active)
  1797. {
  1798.   GimpParam *return_vals;
  1799.   gint nreturn_vals;
  1800.   gboolean success = TRUE;
  1801.  
  1802.   return_vals = gimp_run_procedure ("gimp_image_set_component_active",
  1803.                     &nreturn_vals,
  1804.                     GIMP_PDB_IMAGE, image_ID,
  1805.                     GIMP_PDB_INT32, component,
  1806.                     GIMP_PDB_INT32, active,
  1807.                     GIMP_PDB_END);
  1808.  
  1809.   success = return_vals[0].data.d_status == GIMP_PDB_SUCCESS;
  1810.  
  1811.   gimp_destroy_params (return_vals, nreturn_vals);
  1812.  
  1813.   return success;
  1814. }
  1815.  
  1816. /**
  1817.  * gimp_image_get_component_visible:
  1818.  * @image_ID: The image.
  1819.  * @component: The image component.
  1820.  *
  1821.  * Returns if the specified image's image component is visible.
  1822.  *
  1823.  * This procedure returns if the specified image's image component
  1824.  * (i.e. Red, Green, Blue intensity channels in an RGB image) is
  1825.  * visible or invisible -- whether or not it can be seen. If the
  1826.  * specified component is not valid for the image type, an error is
  1827.  * returned.
  1828.  *
  1829.  * Returns: Component is visible.
  1830.  */
  1831. gboolean
  1832. gimp_image_get_component_visible (gint32          image_ID,
  1833.                   GimpChannelType component)
  1834. {
  1835.   GimpParam *return_vals;
  1836.   gint nreturn_vals;
  1837.   gboolean visible = FALSE;
  1838.  
  1839.   return_vals = gimp_run_procedure ("gimp_image_get_component_visible",
  1840.                     &nreturn_vals,
  1841.                     GIMP_PDB_IMAGE, image_ID,
  1842.                     GIMP_PDB_INT32, component,
  1843.                     GIMP_PDB_END);
  1844.  
  1845.   if (return_vals[0].data.d_status == GIMP_PDB_SUCCESS)
  1846.     visible = return_vals[1].data.d_int32;
  1847.  
  1848.   gimp_destroy_params (return_vals, nreturn_vals);
  1849.  
  1850.   return visible;
  1851. }
  1852.  
  1853. /**
  1854.  * gimp_image_set_component_visible:
  1855.  * @image_ID: The image.
  1856.  * @component: The image component.
  1857.  * @visible: Component is visible.
  1858.  *
  1859.  * Sets if the specified image's image component is visible.
  1860.  *
  1861.  * This procedure sets if the specified image's image component (i.e.
  1862.  * Red, Green, Blue intensity channels in an RGB image) is visible or
  1863.  * invisible -- whether or not it can be seen. If the specified
  1864.  * component is not valid for the image type, an error is returned.
  1865.  *
  1866.  * Returns: TRUE on success.
  1867.  */
  1868. gboolean
  1869. gimp_image_set_component_visible (gint32          image_ID,
  1870.                   GimpChannelType component,
  1871.                   gboolean        visible)
  1872. {
  1873.   GimpParam *return_vals;
  1874.   gint nreturn_vals;
  1875.   gboolean success = TRUE;
  1876.  
  1877.   return_vals = gimp_run_procedure ("gimp_image_set_component_visible",
  1878.                     &nreturn_vals,
  1879.                     GIMP_PDB_IMAGE, image_ID,
  1880.                     GIMP_PDB_INT32, component,
  1881.                     GIMP_PDB_INT32, visible,
  1882.                     GIMP_PDB_END);
  1883.  
  1884.   success = return_vals[0].data.d_status == GIMP_PDB_SUCCESS;
  1885.  
  1886.   gimp_destroy_params (return_vals, nreturn_vals);
  1887.  
  1888.   return success;
  1889. }
  1890.  
  1891. /**
  1892.  * gimp_image_get_filename:
  1893.  * @image_ID: The image.
  1894.  *
  1895.  * Returns the specified image's filename.
  1896.  *
  1897.  * This procedure returns the specified image's filename -- if it was
  1898.  * loaded or has since been saved. Otherwise, returns NULL.
  1899.  *
  1900.  * Returns: The filename.
  1901.  */
  1902. gchar *
  1903. gimp_image_get_filename (gint32 image_ID)
  1904. {
  1905.   GimpParam *return_vals;
  1906.   gint nreturn_vals;
  1907.   gchar *filename = NULL;
  1908.  
  1909.   return_vals = gimp_run_procedure ("gimp_image_get_filename",
  1910.                     &nreturn_vals,
  1911.                     GIMP_PDB_IMAGE, image_ID,
  1912.                     GIMP_PDB_END);
  1913.  
  1914.   if (return_vals[0].data.d_status == GIMP_PDB_SUCCESS)
  1915.     filename = g_strdup (return_vals[1].data.d_string);
  1916.  
  1917.   gimp_destroy_params (return_vals, nreturn_vals);
  1918.  
  1919.   return filename;
  1920. }
  1921.  
  1922. /**
  1923.  * gimp_image_set_filename:
  1924.  * @image_ID: The image.
  1925.  * @filename: The new image filename.
  1926.  *
  1927.  * Sets the specified image's filename.
  1928.  *
  1929.  * This procedure sets the specified image's filename.
  1930.  *
  1931.  * Returns: TRUE on success.
  1932.  */
  1933. gboolean
  1934. gimp_image_set_filename (gint32  image_ID,
  1935.              gchar  *filename)
  1936. {
  1937.   GimpParam *return_vals;
  1938.   gint nreturn_vals;
  1939.   gboolean success = TRUE;
  1940.  
  1941.   return_vals = gimp_run_procedure ("gimp_image_set_filename",
  1942.                     &nreturn_vals,
  1943.                     GIMP_PDB_IMAGE, image_ID,
  1944.                     GIMP_PDB_STRING, filename,
  1945.                     GIMP_PDB_END);
  1946.  
  1947.   success = return_vals[0].data.d_status == GIMP_PDB_SUCCESS;
  1948.  
  1949.   gimp_destroy_params (return_vals, nreturn_vals);
  1950.  
  1951.   return success;
  1952. }
  1953.  
  1954. /**
  1955.  * gimp_image_get_resolution:
  1956.  * @image_ID: The image.
  1957.  * @xresolution: The resolutionin the x-axis, in dots per inch.
  1958.  * @yresolution: The resolutionin the y-axis, in dots per inch.
  1959.  *
  1960.  * Returns the specified image's resolution.
  1961.  *
  1962.  * This procedure returns the specified image's resolution in dots per
  1963.  * inch. This value is independent of any of the layers in this image.
  1964.  *
  1965.  * Returns: TRUE on success.
  1966.  */
  1967. gboolean
  1968. gimp_image_get_resolution (gint32   image_ID,
  1969.                gdouble *xresolution,
  1970.                gdouble *yresolution)
  1971. {
  1972.   GimpParam *return_vals;
  1973.   gint nreturn_vals;
  1974.   gboolean success = TRUE;
  1975.  
  1976.   return_vals = gimp_run_procedure ("gimp_image_get_resolution",
  1977.                     &nreturn_vals,
  1978.                     GIMP_PDB_IMAGE, image_ID,
  1979.                     GIMP_PDB_END);
  1980.  
  1981.   *xresolution = 0.0;
  1982.   *yresolution = 0.0;
  1983.  
  1984.   success = return_vals[0].data.d_status == GIMP_PDB_SUCCESS;
  1985.  
  1986.   if (success)
  1987.     {
  1988.       *xresolution = return_vals[1].data.d_float;
  1989.       *yresolution = return_vals[2].data.d_float;
  1990.     }
  1991.  
  1992.   gimp_destroy_params (return_vals, nreturn_vals);
  1993.  
  1994.   return success;
  1995. }
  1996.  
  1997. /**
  1998.  * gimp_image_set_resolution:
  1999.  * @image_ID: The image.
  2000.  * @xresolution: The new image resolution in the x-axis, in dots per inch.
  2001.  * @yresolution: The new image resolution in the y-axis, in dots per inch.
  2002.  *
  2003.  * Sets the specified image's resolution.
  2004.  *
  2005.  * This procedure sets the specified image's resolution in dots per
  2006.  * inch. This value is independent of any of the layers in this image.
  2007.  * No scaling or resizing is performed.
  2008.  *
  2009.  * Returns: TRUE on success.
  2010.  */
  2011. gboolean
  2012. gimp_image_set_resolution (gint32  image_ID,
  2013.                gdouble xresolution,
  2014.                gdouble yresolution)
  2015. {
  2016.   GimpParam *return_vals;
  2017.   gint nreturn_vals;
  2018.   gboolean success = TRUE;
  2019.  
  2020.   return_vals = gimp_run_procedure ("gimp_image_set_resolution",
  2021.                     &nreturn_vals,
  2022.                     GIMP_PDB_IMAGE, image_ID,
  2023.                     GIMP_PDB_FLOAT, xresolution,
  2024.                     GIMP_PDB_FLOAT, yresolution,
  2025.                     GIMP_PDB_END);
  2026.  
  2027.   success = return_vals[0].data.d_status == GIMP_PDB_SUCCESS;
  2028.  
  2029.   gimp_destroy_params (return_vals, nreturn_vals);
  2030.  
  2031.   return success;
  2032. }
  2033.  
  2034. /**
  2035.  * gimp_image_get_unit:
  2036.  * @image_ID: The image.
  2037.  *
  2038.  * Returns the specified image's unit.
  2039.  *
  2040.  * This procedure returns the specified image's unit. This value is
  2041.  * independent of any of the layers in this image. See the gimp_unit_*
  2042.  * procedure definitions for the valid range of unit IDs and a
  2043.  * description of the unit system.
  2044.  *
  2045.  * Returns: The unit.
  2046.  */
  2047. GimpUnit
  2048. gimp_image_get_unit (gint32 image_ID)
  2049. {
  2050.   GimpParam *return_vals;
  2051.   gint nreturn_vals;
  2052.   GimpUnit unit = 0;
  2053.  
  2054.   return_vals = gimp_run_procedure ("gimp_image_get_unit",
  2055.                     &nreturn_vals,
  2056.                     GIMP_PDB_IMAGE, image_ID,
  2057.                     GIMP_PDB_END);
  2058.  
  2059.   if (return_vals[0].data.d_status == GIMP_PDB_SUCCESS)
  2060.     unit = return_vals[1].data.d_unit;
  2061.  
  2062.   gimp_destroy_params (return_vals, nreturn_vals);
  2063.  
  2064.   return unit;
  2065. }
  2066.  
  2067. /**
  2068.  * gimp_image_set_unit:
  2069.  * @image_ID: The image.
  2070.  * @unit: The new image unit.
  2071.  *
  2072.  * Sets the specified image's unit.
  2073.  *
  2074.  * This procedure sets the specified image's unit. No scaling or
  2075.  * resizing is performed. This value is independent of any of the
  2076.  * layers in this image. See the gimp_unit_* procedure definitions for
  2077.  * the valid range of unit IDs and a description of the unit system.
  2078.  *
  2079.  * Returns: TRUE on success.
  2080.  */
  2081. gboolean
  2082. gimp_image_set_unit (gint32   image_ID,
  2083.              GimpUnit unit)
  2084. {
  2085.   GimpParam *return_vals;
  2086.   gint nreturn_vals;
  2087.   gboolean success = TRUE;
  2088.  
  2089.   return_vals = gimp_run_procedure ("gimp_image_set_unit",
  2090.                     &nreturn_vals,
  2091.                     GIMP_PDB_IMAGE, image_ID,
  2092.                     GIMP_PDB_INT32, unit,
  2093.                     GIMP_PDB_END);
  2094.  
  2095.   success = return_vals[0].data.d_status == GIMP_PDB_SUCCESS;
  2096.  
  2097.   gimp_destroy_params (return_vals, nreturn_vals);
  2098.  
  2099.   return success;
  2100. }
  2101.  
  2102. /**
  2103.  * gimp_image_get_layer_by_tattoo:
  2104.  * @image_ID: The image.
  2105.  * @tattoo: The tattoo of the layer to find.
  2106.  *
  2107.  * Find a layer with a given tattoo in an image.
  2108.  *
  2109.  * This procedure returns the layer with the given tattoo in the
  2110.  * specified image.
  2111.  *
  2112.  * Returns: The layer with the specified tattoo.
  2113.  */
  2114. gint32
  2115. gimp_image_get_layer_by_tattoo (gint32 image_ID,
  2116.                 gint   tattoo)
  2117. {
  2118.   GimpParam *return_vals;
  2119.   gint nreturn_vals;
  2120.   gint32 layer_ID = -1;
  2121.  
  2122.   return_vals = gimp_run_procedure ("gimp_image_get_layer_by_tattoo",
  2123.                     &nreturn_vals,
  2124.                     GIMP_PDB_IMAGE, image_ID,
  2125.                     GIMP_PDB_INT32, tattoo,
  2126.                     GIMP_PDB_END);
  2127.  
  2128.   if (return_vals[0].data.d_status == GIMP_PDB_SUCCESS)
  2129.     layer_ID = return_vals[1].data.d_layer;
  2130.  
  2131.   gimp_destroy_params (return_vals, nreturn_vals);
  2132.  
  2133.   return layer_ID;
  2134. }
  2135.  
  2136. /**
  2137.  * gimp_image_get_channel_by_tattoo:
  2138.  * @image_ID: The image.
  2139.  * @tattoo: The tattoo of the channel to find.
  2140.  *
  2141.  * Find a channel with a given tattoo in an image.
  2142.  *
  2143.  * This procedure returns the channel with the given tattoo in the
  2144.  * specified image.
  2145.  *
  2146.  * Returns: The channel with the specified tattoo.
  2147.  */
  2148. gint32
  2149. gimp_image_get_channel_by_tattoo (gint32 image_ID,
  2150.                   gint   tattoo)
  2151. {
  2152.   GimpParam *return_vals;
  2153.   gint nreturn_vals;
  2154.   gint32 channel_ID = -1;
  2155.  
  2156.   return_vals = gimp_run_procedure ("gimp_image_get_channel_by_tattoo",
  2157.                     &nreturn_vals,
  2158.                     GIMP_PDB_IMAGE, image_ID,
  2159.                     GIMP_PDB_INT32, tattoo,
  2160.                     GIMP_PDB_END);
  2161.  
  2162.   if (return_vals[0].data.d_status == GIMP_PDB_SUCCESS)
  2163.     channel_ID = return_vals[1].data.d_channel;
  2164.  
  2165.   gimp_destroy_params (return_vals, nreturn_vals);
  2166.  
  2167.   return channel_ID;
  2168. }
  2169.